Claude Code 攻略 3 - 使用 Claude Code 的 Plan Mode 让事情事半功倍

从一个典型场景说起#

在学习了 Claude Code 的发展历史和上下文工程之后，我开始频繁使用它来处理日常开发任务。但很快我发现了一个让人困惑的现象：

有时候，我说"帮我实现用户认证功能"，Claude Code 会先进入一个"Plan Mode"，探索代码结构、生成实现方案，等我确认后才开始执行。但有时候，同样的需求描述，它却直接开始写代码，写到一半才发现方向不对，浪费了不少 Token 和时间。

这种不一致性让我开始思考：Claude Code 到底是如何决定什么时候该先规划、什么时候直接执行的？我能不能主动控制这个流程？

经过一段时间的摸索和实践，我逐渐理解了 Claude Code 的工作流程决策机制，也找到了一些引导它的有效方法。这篇文章，我会分享这些实践经验，帮助你更好地掌握 Claude Code 的使用姿势。

Claude Code 的决策流程：何时规划 vs 直接执行#

决策逻辑：任务复杂度评估#

Claude Code 在接到任务时，会进行快速的复杂度评估，决定是直接执行还是进入 Plan Mode：

用户需求
   ↓
任务复杂度评估
   - 是否涉及多个文件？
   - 是否需要多步骤操作？
   - 是否有多种实现方案？
   - 是否可能影响现有功能？
   ↓
简单任务 → 直接执行
复杂任务 → 进入 Plan Mode

判断标准与实际案例#

直接执行的场景#

在我的观察中，以下场景 Claude Code 通常会直接执行：

类型 1：微调整

修改文案、错别字
添加单个依赖
删除无用文件

你：把标题改得更吸引人一些
Claude Code：[直接修改]

你：添加 lodash 依赖
Claude Code：npm install lodash

类型 2：单一操作

单个函数的简单修改
配置文件的微小调整

你：把这个函数改成箭头函数
Claude Code：[直接修改代码]

容易产生歧义的场景#

中等复杂度任务：

添加单个功能（但可能涉及多个文件）
修复 Bug（但可能需要调试）
小范围重构

你：帮我实现用户登录功能
Claude Code：可能直接开始写代码
建议：明确要求先规划

建议规划的场景#

根据我的经验，以下场景最好让 Claude Code 先做规划：

复杂任务：

实现认证系统
架构重构
数据迁移
性能优化

你：重构整个认证模块
Claude Code：进入 Plan Mode

你：优化数据库查询性能
Claude Code：进入 Plan Mode

为什么会出现"应该规划却直接执行"？#

系统提示词倾向：Claude Code 的默认提示词倾向于直接执行任务，以体现效率。

规划条件判断：内部对"复杂任务"的判断可能不够准确。

用户描述模糊：如果用户描述不够具体，可能被误解为简单任务。

Plan Mode 的完整工作流程：五个阶段的深度解析#

当 Claude Code 决定进入 Plan Mode 后，会执行一套完整的工作流程，确保方案的合理性和可行性。

Phase 1：初始理解（Initial Understanding）#

目标：理解需求 + 探索代码库结构

核心机制：

最多启动 3 个 Explore Agent 并行探索
每个 Agent 负责不同的探索方向
只探索相关内容，避免读取整个代码库

在我实际使用中，Explore Agent 的工作方式是这样的：

任务：添加用户认证功能

Explore Agent 1：寻找现有的认证相关文件
├─ Glob: **/*auth*.ts, **/*login*.ts
├─ Grep: "authentication", "login", "jwt"
└─ Read: src/auth/auth.service.ts

Explore Agent 2：了解项目结构和技术栈
├─ Read: package.json（依赖）
├─ Read: next.config.js（框架配置）
└─ Glob: src/**/*.ts（文件结构）

Explore Agent 3：检查数据库模型
├─ Grep: "User", "user", "model"
└─ Read: src/models/user.ts

最后输出一个包含代码结构理解、相关文件清单和技术栈分析的报告。

Phase 2：设计（Design）#

目标：基于探索结果，设计实现方案

核心机制：

启动 1 个 Plan Agent
基于探索结果进行方案设计
考虑依赖关系和实现顺序

设计示例：

## 用户认证功能实现方案

### 技术选择

- 认证方式：JWT Token
- 密码加密：bcrypt
- 数据库：现有 PostgreSQL

### 实现步骤

1. 创建 User 实体（已有，需验证）
2. 实现 Auth Service（登录、注册、验证）
3. 创建 Auth Controller（API 端点）
4. 添加 JWT 中间件
5. 编写测试用例

### 文件清单

- src/services/auth.service.ts（新建）
- src/controllers/auth.controller.ts（新建）
- src/middleware/auth.middleware.ts（新建）
- src/utils/jwt.ts（工具函数）

Phase 3：审查（Review）#

目标：确保方案合理，发现潜在问题

核心机制：

读取关键文件验证假设
与用户确认有歧义的部分
使用 AskUserQuestion 获取决策

审查示例：

发现的问题：
1. 项目已有 Prisma ORM，需要使用 Prisma 的用户模型
2. 需要确认是否支持角色权限（RBAC）
3. 需要确认 token 过期时间

询问用户：
- 是否需要角色权限管理？
- token 过期时间设置为多久？
- 是否需要刷新 token 机制？

Phase 4：最终计划（Final Plan）#

目标：生成可执行的计划文档

输出位置：.claude/plans/xxx.md

计划格式：

# 实现用户认证功能

## 概述

为 Next.js 项目添加完整的用户认证系统

## 实现步骤

### 步骤 1：验证和更新 User 模型

- 文件：prisma/schema.prisma
- 操作：添加缺失字段（emailVerified 等）

### 步骤 2：实现认证服务

- 文件：src/services/auth.service.ts
- 功能：注册、登录、token 验证

### 步骤 3：创建 API 路由

- 文件：src/app/api/auth/\*_/_.ts
- 端点：/api/auth/register, /api/auth/login

### 步骤 4：添加中间件

- 文件：src/middleware/auth.ts
- 功能：token 验证和用户识别

### 步骤 5：编写测试

- 文件：tests/auth.test.ts
- 测试：注册、登录、权限验证

## 需要确认的问题

- [x] 使用 JWT 认证
- [x] token 过期时间：7 天
- [ ] 是否需要角色权限？→ 待确认

Phase 5：退出 Plan Mode#

工具：ExitPlanMode

等待用户确认：是否执行计划

Explore Agent 的高效探索机制#

为什么需要 Explore Agent？#

传统做法的问题：

Read 所有文件 → 消耗大量 Token
读取速度慢 → 可能超限
信息过载 → 难以找到关键内容

Explore Agent 的创新：

Glob 查找文件模式 → 精确定位
Grep 搜索关键词 → 智能筛选
Read 关键部分 → 重点采样

实际工作案例#

任务：在现有项目中添加支付功能

低效方式：

# 读取所有文件（假设有 1000 个文件）
Read src/**/*.ts → 50万行代码 → 超出 Token 限制

Explore Agent 方式：

// Agent 1：寻找现有支付相关代码
Glob.search("**/*payment*.ts", "**/*stripe*.ts");
Grep.search("payment", "stripe", "billing");
// 找到：src/utils/stripe.ts（已有的 stripe 配置）

// Agent 2：了解订单系统
Grep.search("order", "purchase", "checkout");
// 找到：src/models/order.ts, src/services/order.service.ts

// Agent 3：检查环境配置
Read(".env.example", "package.json");
// 发现：已有 stripe 依赖，缺少 webhook 配置

输出报告：

探索结果：
1. 项目已有 Stripe 集成基础
2. 订单系统完整，包含状态管理
3. 缺少 webhook 处理和支付状态更新
4. 建议复用现有 stripe 配置

探索策略的最佳实践#

策略 1：关键词扩展

核心词：payment
扩展词：billing, checkout, purchase, transaction, stripe, paypal

策略 2：文件名模式

直接模式：*payment*, *billing*
间接模式：*order*, *checkout*, *subscription*

策略 3：代码搜索优先级

优先级 1：类型定义（*.d.ts, interface, type）
优先级 2：服务层（service, manager, handler）
优先级 3：API 层（route, controller, api）
优先级 4：配置文件（config, env, setting）

Plan Agent 的任务拆解逻辑#

拆解原则#

原则 1：单一职责 每个步骤只做一件事，避免复杂步骤。

❌ 不好的拆解：

步骤 1：实现用户注册和登录功能

✅ 好的拆解：

步骤 1：创建用户注册 API
步骤 2：实现密码加密
步骤 3：生成 JWT token
步骤 4：创建用户登录 API

原则 2：依赖顺序 按照依赖关系排序，确保执行顺序合理。

依赖链：
JWT 工具函数 → Auth Service → Auth Controller → API 路由

正确的步骤顺序：
1. 实现 JWT 工具函数
2. 创建 Auth Service
3. 实现 Auth Controller
4. 添加 API 路由

原则 3：可测试性 每个步骤都可以独立验证和测试。

步骤 2：Auth Service 实现
测试验证：单元测试 service 方法
预期结果：register() 返回用户对象，login() 返回 token

实际拆解案例#

需求：实现博客文章的评论系统

Plan Agent 的拆解过程：

初步需求：
添加评论功能

第一步：拆解核心功能
├─ 评论模型（数据结构）
├─ 评论 API（增删改查）
├─ 评论显示（前端组件）
└─ 评论通知（可选）

第二步：细化每个功能
评论模型：
├─ 创建 Comment 实体
├─ 定义字段（id, content, author, postId, createdAt）
└─ 设置数据库关系

评论 API：
├─ GET /api/posts/:id/comments（获取评论）
├─ POST /api/posts/:id/comments（添加评论）
├─ PUT /api/comments/:id（修改评论）
└─ DELETE /api/comments/:id（删除评论）

评论显示：
├─ 评论列表组件
├─ 单条评论组件
├─ 评论表单组件
└─ 分页组件

第三步：排列执行顺序
1. 数据库模型（基础）
2. API 实现（后端）
3. 前端组件（展示）
4. 集成测试（验证）

正确的使用姿势和最佳实践#

任务分类与引导策略#

根据任务类型，采用不同的引导策略：

任务类型	规划需求	引导方式	示例
微调整	❌ 不需要	直接描述	"把标题改得更吸引人"
单一操作	❌ 不需要	明确指令	"删除这个未使用的文件"
小功能	⚠️ 建议	明确要求规划	"先规划，帮我添加搜索功能"
中等功能	✅ 必须	强制规划	"进入 Plan Mode，设计用户系统"
大功能	✅ 必须	分阶段规划	"第一阶段：先设计认证方案"

主动触发 Plan Mode 的方法#

方法 1：显式要求规划#

我现在养成了一个习惯：对于稍微复杂一点的任务，都会明确要求先规划。

不够明确的说法："帮我实现用户认证"
更好的说法："先进入 Plan Mode，帮我设计用户认证的实现方案"

方法 2：强调探索和理解#

另一个有效的方法是强调"先探索"：

"先了解现有代码架构，然后给我一个用户认证功能的实现方案"
"探索一下项目的支付相关代码，然后设计退款功能的实现计划"

方法 3：提出问题引导思考#

有时候我会用提问的方式，让它主动进入思考模式：

"我想添加用户认证，你觉得有哪些实现方式？各有什么优缺点？"
"这个重构任务有几种实现方案？帮我分析一下利弊"

项目级配置：强制规划策略#

在 CLAUDE.md 中添加工作流程要求：

## 工作流程要求

当接到以下类型的任务时，必须先进入 Plan Mode：

### 强制规划任务

1. **新功能开发**

   - 代码超过 50 行
   - 涉及新的数据模型
   - 需要新的 API 端点

2. **架构修改**

   - 修改现有功能的核心逻辑
   - 调整文件结构
   - 更新技术栈

3. **多文件协调**

   - 涉及 3 个以上文件的修改
   - 需要跨模块的协调
   - 影响多个功能模块

4. **数据相关**
   - 数据库迁移
   - 数据结构变更
   - API 接口变更

### 执行流程

1. 接到任务 → 检查是否匹配强制规划条件
2. 匹配 → 自动进入 Plan Mode
3. 不匹配 → 直接执行（但仍可手动要求规划）

常见问题的解决策略#

问题 1：AI 直接执行，但方向错误#

解决方案：

你：停止执行，先进入 Plan Mode
Claude Code：[停止当前操作，进入规划模式]

预防措施：

任务描述时使用"设计"、"方案"、"规划"等关键词
复杂任务开始前明确要求："先给我一个实现方案"

问题 2：规划过于详细，执行缓慢#

解决方案：

你：规划很好，但可以分阶段执行。先执行第一阶段
Claude Code：[执行第一阶段的步骤]

平衡策略：

大任务分阶段规划和执行
每个阶段包含 3-5 个步骤
完成阶段后评估再继续

问题 3：探索不够全面，遗漏重要文件#

解决方案：

你：探索一下是否还有其他相关的配置文件
Claude Code：[启动额外的 Explore Agent]

预防措施：

提供相关线索："项目使用了 TypeORM 和 Redis"
要求多角度探索："从配置、模型、API 三个角度探索"

完整工作流程图#

graph TD
    A[用户提出需求] --> B{任务复杂度评估}

    B -->|简单任务| C[直接执行]
    B -->|复杂任务| D[进入 Plan Mode]

    D --> E[Phase 1: 初始理解]
    E --> F[Explore Agent 探索]
    F --> G[生成探索报告]

    G --> H[Phase 2: 设计方案]
    H --> I[Plan Agent 设计]
    I --> J[生成初步方案]

    J --> K[Phase 3: 审查]
    K --> L{需要用户确认?}
    L -->|是| M[AskUserQuestion]
    L -->|否| N[Phase 4: 最终计划]
    M --> O[获取用户反馈]
    O --> N

    N --> P[写入计划文件]
    P --> Q[Phase 5: 退出 Plan Mode]

    Q --> R{用户确认执行?}
    R -->|确认| S[按计划执行]
    R -->|调整| T[修改计划]
    R -->|取消| U[任务结束]

    T --> S
    C --> V[任务完成]
    S --> V